home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / proto212.zip / PROTOE.MAN < prev    next >
Text File  |  1992-01-14  |  48KB  |  1,232 lines
  1.  
  2.  
  3. 1        Introduction and warnings                                         1
  4. 1.1      Why use an extractor                                              1
  5. 1.1.1    Delivery of a library with invalid prototypes                     1
  6. 1.1.2    Implicit validation of prototypes in header file                  1
  7. 1.1.3    Patching calls right after a function revision                    1
  8. 1.2      Some compilers support prototype extraction                       2
  9. 1.2.1    A compiler may forgot prototypes                                  2
  10. 2        Limits of the shareware version                                   2
  11. 2.1      Automatic summary                                                 2
  12. 2.2      Permuted index                                                    3
  13. 2.3      Historic of system's functions                                    3
  14. 3        Specification and operation                                       3
  15. 3.1      General principal                                                 3
  16. 3.1.1    System, users and suppliers: A programmer's view                  3
  17. 3.1.2    function declaration (prototypes) vs function definition          4
  18. 3.1.2.1  Purpose of function prototypes                                    4
  19. 3.1.2.2  How to use prototypes                                             5
  20. 3.1.2.3  Which prototypes must be supplied in a header file                5
  21. 3.2      ANSI C and C++ supported                                          5
  22. 3.3      Added keyword to automate operation of the extractor              5
  23. 3.3.1    Added keyword definition                                          6
  24. 3.4      Command line options                                              6
  25. 3.4.1    @file : file holding command line options                         6
  26. 3.4.1.1  Example of command file search                                    6
  27. 3.4.1.2  @ without file argument                                           7
  28. 3.4.2    -a : Default access control for member function (C++)             7
  29. 3.4.3    -b : Update C++ header file from a .pm file                       8
  30. 3.4.3.1  Example of option -b use                                          8
  31. 3.4.3.2  Distribution control of class member prototypes in a file         8
  32. 3.4.4    -c : Output selection                                             9
  33. 3.4.4.1  Export : An extension to C                                        9
  34.          How to add export to C language                                   9
  35.          Why using export                                                  9
  36.          _export verb                                                     10
  37. 3.4.4.2  Options -c and -f specified more than once                       10
  38. 3.4.4.3  Selection i of the -c option                                     10
  39. 3.4.4.4  Selection d of the -c option                                     10
  40. 3.4.4.5  Corrections to prototype before generation                       11
  41.          Function without explicit return type                            11
  42.          Typeless parameters                                              11
  43.          Function without parameter                                       11
  44. 3.4.5    -C : Disallow nested comments                                    11
  45. 3.4.6    -d : Symbol definition                                           11
  46. 3.4.7    -e : Close an output file                                        12
  47. 3.4.7.1  protection against processing twice the same file                12
  48.          Source files spread in two directories                           12
  49. 3.4.8    -f/+f : Specification of an output file                          12
  50. 3.4.8.1  Options -c and -f specified more than once                       13
  51. 3.4.9    -h : Prototype file to split into class related header           13
  52. 3.4.10   -i : Incremental mode                                            13
  53. 3.4.11   -I : Search path for include files                               13
  54. 3.4.12   -k : Renaming of keyword use by the extractor                    14
  55. 3.4.13   -l : Alternate name for -h option                                14
  56. 3.4.14   -m : Prepackaged options combinations                            14
  57. 3.4.14.1 Option -m1 : Optional output directory                           15
  58. 3.4.15   -o : Alternative name for option -m                              15
  59. 3.4.16   -p : Activate processing for following files                     15
  60.  
  61.  
  62.  
  63.                                                               1
  64.  
  65.  
  66. 3.4.16.1 Example of -p and -x uses                                        15
  67. 3.4.16.2 protection against processing twice the same file                15
  68. 3.4.17   -P : Preprocessor on                                             15
  69. 3.4.17.1 Processing of #define while full preprocessor is NOT active      16
  70. 3.4.17.2 Processing of #if and #ifdef without -P option                   16
  71. 3.4.18   Silent operation                                                 16
  72. 3.4.19   -t : source is read from the console (stdin)                     16
  73. 3.4.20   -v : List of source files processed                              16
  74. 3.4.21   -x : Do not process following source files                       16
  75. 3.4.21.1 Example of -p and -x uses                                        16
  76. 3.4.21.2 protection against processing twice the same file                17
  77. 3.4.22   Macros and special character                                     17
  78. 3.4.22.1 $ : current directory name                                       17
  79. 3.5      Invalid options combinations                                     17
  80. 3.6      Suggested uses of the extractor                                  17
  81. 3.6.1    warning about this section                                       18
  82. 3.6.2    The directory is the basic organizationnal unit                  18
  83. 3.6.3    Names for header file                                            18
  84. 3.6.4    File locally generated                                           18
  85. 3.6.5    Files exported to users                                          18
  86. 3.6.5.1  Export : An extension to C                                       19
  87. 3.6.6    One header file, different views for users and members           19
  88.  
  89.  
  90. 1        Introduction and warnings                                   
  91.  
  92.     The prototype extractor automates part of an ANSI C and C++ 
  93.     2.0 programmer's work. It also supports K&R functions 
  94.     declaration syntax.
  95.  
  96.     This utility is available for both MSDOS(PCDOS) (3.0 and 
  97.     up), SCO XENIX version 2.3 (UNIX système V.3.2) et SUN SPARC 
  98.     (Sunos).
  99.  
  100.     This manual applies to all three systems. However, the / 
  101.     field separator has been used for file specification. The 
  102.     MSDOS version used the \ character instead.
  103.  
  104. 1.1      Why use an extractor                                        
  105.  
  106.     Use of an automatic tool to generate prototypes is 
  107.     optionnal. Prototypes may be written manually into header 
  108.     files. Program without proper prototypes will compile under 
  109.     ANSI C mostly for compatibility with K&R convention. Under 
  110.     C++, prototypes are not an option.
  111.  
  112.     In this section, we will not show the importance of 
  113.     prototypes. Instead, we will focus on the importance of an 
  114.     automatic extraction tool.
  115.  
  116. 1.1.1    Delivery of a library with invalid prototypes               
  117.  
  118.     During the maintenance of a software sub-system, functions 
  119.     are added, deleted and modified. Reliability of prototypes 
  120.     is essential at delivery time. Often, prototype related 
  121.     problems will be detected by a different team. The updated 
  122.     package will be the last suspect. Programmer will really 
  123.     wonder: the project compiles ok but crashes abruptly.
  124.  
  125.     In C this kind of problem may take days to locate. In C++, 
  126.     the problem will be catch at link time. In all case, it 
  127.     means waste of time, and disatisfaction.
  128.  
  129. 1.1.2    Implicit validation of prototypes in header file            
  130.  
  131.     There is simple way of checking the correctness of 
  132.     prototypes in a header. You simply include the header in 
  133.     each source that declare those function. Recompiling those 
  134.     sources will test that the prototypes correspond to the 
  135.     declaration.
  136.  
  137.     This method does not detect missing prototypes (some 
  138.     functions are simply never called from the package itself) 
  139.     nor prototypes of obsolete functions. Using C++, this method 
  140.     is simply useless. Several C++ functions may share the same 
  141.     name: The compiler sees an invalid prototype as an overload 
  142.     function.
  143.  
  144. 1.1.3    Patching calls right after a function revision              
  145.  
  146.  
  147.  
  148.  
  149.  
  150.                                                               1
  151.  
  152.  
  153.     One way of avoiding problems when we modified the 
  154.     declaration of a function is to correct all the calls to 
  155.     this function as soon as possible. Most programmers will 
  156.     locate the calls before changing the function just to 
  157.     evaluate the cost of the modification. They will GREP around 
  158.     using the function name as a key.
  159.  
  160.     Doing so is ok, but not totally safe. Client function may be 
  161.     located on another computer, or simply in a project unknown 
  162.     to the programmer.
  163.  
  164.     Locating calls to a class member C++ function is almost 
  165.     impossible using GREP. The programmers must use cross 
  166.     reference and other gadgets.
  167.  
  168.     The only proof will occur when client project will be 
  169.     recompiled. This may append several days or several months 
  170.     after the revision. Accurate prototypes are the key to safe 
  171.     rebuilds.
  172.  
  173. 1.2      Some compilers support prototype extraction                 
  174.  
  175.     Some compilers have an option to extract prototypes while 
  176.     compiling. Such an option suffers high performance drawback 
  177.     and is used only when nothing else is available.
  178.  
  179.     Prototypes must be extracted prior to compilation; valid 
  180.     prototypes are necessary for the compilation to succeed. If 
  181.     a compiler is used to extract prototypes, two compilation 
  182.     passes will be necessary, one to get the prototypes, and one 
  183.     to do compilation.
  184.  
  185. 1.2.1    A compiler may forgot prototypes                            
  186.  
  187.     If one uses a compiler to extract prototypes, problems may 
  188.     arise. The compiler may very well stop the compilation 
  189.     process because too many errors where met. Functions not 
  190.     compiled won't get a prototype. Several errors might be 
  191.     caused by the absence of those prototypes.
  192.  
  193. 2        Limits of the shareware version                             
  194.  
  195.     This manual presents every options of the extractor.
  196.  
  197.     Some options are not available for the shareware version. 
  198.     The license explains how to get a complete version.
  199.  
  200.     The user who registers will receive an up to date version 
  201.     with all features and few companion utilities. These are 
  202.     documented here. The list may change without notice.
  203.  
  204. 2.1      Automatic summary                                           
  205.  
  206.     One utility builds a summary: For each function, one comment 
  207.     line is extracted from the source. The line is chosen using 
  208.     a simple convention.
  209.  
  210.  
  211.  
  212.  
  213.                                                               2
  214.  
  215.  
  216.     The output file has the following layout:
  217.  
  218.       function_a : short description of function_a
  219.       ...
  220.       function_z : short description of function_z
  221.  
  222.     The first comment line of the comment block preceding the 
  223.     function definition is selected.
  224.  
  225. 2.2      Permuted index                                              
  226.  
  227.     Using the summary, one utility creats a permuted index based 
  228.     on meaningful words of the short description. From the 
  229.     following example summary:
  230.  
  231.       button_creation: creation and initialization of a button
  232.       button_erase: erases and frees a button from memory
  233.  
  234.     Each useful words from the description will be used as a 
  235.     key. This allows location of a function using any keywords 
  236.     (creation, initialization, button, erases, frees, memory).
  237.  
  238. 2.3      Historic of system's functions                              
  239.  
  240.     One file is maintained from the prototype & documentation 
  241.     file produced by the extractor.
  242.  
  243.     It is a text file. It holds a complete prototype of each 
  244.     function, its surrounding comments and a creation or 
  245.     revision date. Each time the system is revised, this file is 
  246.     updated. Information is appended to it, telling which 
  247.     function has changed (ASCII comparison of the commented 
  248.     declaration) , which one is new, and which one has been 
  249.     removed.
  250.  
  251.     A programmer may easily follow the evolution of a system 
  252.     (what's new, what's changed, ...).
  253.  
  254. 3        Specification and operation                                 
  255.  
  256.     Description of the extractor's features. This manual is an 
  257.     operation guide, but suggest ways to apply the product.
  258.  
  259. 3.1      General principal                                           
  260.  
  261.     The extractor may be used for small projects made of few 
  262.     files up too huge project: Several hundredth files split 
  263.     into several directories.
  264.  
  265. 3.1.1    System, users and suppliers: A programmer's view            
  266.  
  267.     Within this manual, the words 'system', 'user', and 
  268.     'supplier' will be used.
  269.  
  270.  
  271.  
  272.  
  273.  
  274.                                                               3
  275.  
  276.  
  277.     A system (often called package or library) is a collection 
  278.     of related functions providing a mean to perform some 
  279.     specific tasks. An example of such system are the str____() 
  280.     functions delivered with most C compiler (strcmp, strlen, 
  281.     strcpy, strchr, ...). The system is a supplier and the 
  282.     sources from which it is builted are members.
  283.  
  284.     One who is calling those functions from his programs or 
  285.     functions is a user. These functions are users of the 
  286.     system. Within this manual, a user is a function that makes 
  287.     use of a system.
  288.  
  289. 3.1.2    function declaration (prototypes) vs function definition    
  290.  
  291.     The major difference between ANSI C compiler an non ANSI 
  292.     compiler is the function prototyping. This provides a way to 
  293.     write the formal interface of a function without supplying 
  294.     the complete source.
  295.  
  296.     Given the definition of function max():
  297.  
  298.       int max(int a, int b)
  299.       {
  300.           if (a<b) return (b);
  301.           return (a);
  302.       }
  303.  
  304.     Here is the declaration or prototype:
  305.  
  306.       int max (int a, int b);
  307.  
  308. 3.1.2.1  Purpose of function prototypes                              
  309.  
  310.     Function prototypes supply needed information to compilers 
  311.     allowing complete type checking of the uses of the function 
  312.     (call). It is then possible to implement a function in one 
  313.     source file and to use it in an other file with full 
  314.     confidence.
  315.  
  316.     The compiler, having access to the prototype of a function, 
  317.     can validate each calls to the function. It checks the 
  318.     argument's count and type of each one, providing conversion 
  319.     when needed and possible. In the following example, each 
  320.     call to the max function will be flag by an ANSI compiler. 
  321.     However, for this to happen, the prototype of max must be 
  322.     supply before the calls.
  323.  
  324.       int max(int a, int b);
  325.  
  326.           ...
  327.           char *pt = max ("xyz","zzz");   /* Invalid arguments */
  328.           int m = max (1,2,3);            /* Argument count */
  329.  
  330.  
  331.  
  332.  
  333.                                                               4
  334.  
  335.  
  336. 3.1.2.2  How to use prototypes                                       
  337.  
  338.     Generally, we put function prototypes in a header file 
  339.     (*.h). For each system, we provided a header file supplying 
  340.     data definitions, macros, and function prototypes. Several 
  341.     header files are supplied with the compiler you are using. 
  342.     Most header files hold function prototypes.
  343.  
  344.     User functions must then include those headers in order to 
  345.     compile safely.
  346.  
  347.     example:
  348.  
  349.       #include <string.h>
  350.  
  351.       ...
  352.       char *pt = strlen("....."); /* prototype of strlen() is provided */
  353.                                   /* in string.h */
  354.  
  355. 3.1.2.3  Which prototypes must be supplied in a header file          
  356.  
  357.     The header file supplied with a system does not held the 
  358.     prototypes of every functions in that system.
  359.  
  360.     "Static" functions are not provided, since they can't be 
  361.     called from outside the source where they appear. Some non 
  362.     "static" functions are not provided because their use is not 
  363.     recommended for user functions. These functions are internal 
  364.     to a system.
  365.  
  366.     Header files are built for specific audiences. They only 
  367.     provide useful prototypes. From that perspective, one may 
  368.     choose to provide two header files for a given system, one 
  369.     used by member functions and one used by user functions.
  370.  
  371.     The extractor provides a mean to create headers selectively.
  372.  
  373. 3.2      ANSI C and C++ supported                                    
  374.  
  375.     The extractor processes C and C++ syntax. No special switche 
  376.     must be supplied. Some switches allow extraction of special 
  377.     prototypes such as member functions.
  378.  
  379. 3.3      Added keyword to automate operation of the extractor        
  380.  
  381.     C++ and C do not allow fully automatic prototype extraction. 
  382.     They are missing keywords for access control. The extractor 
  383.     need specific information to distribute properly prototypes 
  384.     in header files.
  385.  
  386.     The extractor supports seven special keywords.
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                                                               5
  395.  
  396.  
  397.       export      C et C++
  398.       _export     C et C++
  399.       PRIVATE     C++
  400.       PUBLIC      C++
  401.       PROTECTED   C++
  402.       STATIC      C++
  403.       VIRTUAL     C++
  404.  
  405. 3.3.1    Added keyword definition                                    
  406.  
  407.     Most C and C++ compilers do not support keyword export, 
  408.     _export, PRIVATE, PROTECTED, PUBLIC and VIRTUAL. A null 
  409.     definition must be provided to the preprocessor. This can be 
  410.     done using either a preprocessor or compiler command line 
  411.     option (generally -d) or simply putting these six lines in a 
  412.     header file.
  413.  
  414.       #define export
  415.       #define _export
  416.       #define PUBLIC
  417.       #define PRIVATE
  418.       #define PROTECTED
  419.       #define VIRTUAL
  420.  
  421. 3.4      Command line options                                        
  422.  
  423.     This section describes the options that may be specified on 
  424.     the command line. An option is specified by a '-' followed 
  425.     by a letter, optionally followed by a character string.
  426.  
  427.       -x
  428.       -ceoi
  429.       -ffile.nar
  430.  
  431. 3.4.1    @file : file holding command line options                   
  432.  
  433.     If a command line parameter begins with @, it will be taken 
  434.     as a file name. This file holds other parameters.
  435.  
  436.     The file name may specify a directory or not. If the file 
  437.     name holds a directory path, this path will be used and its 
  438.     ancestors to locate the file.
  439.  
  440.     If the file name holds no directory path, the current 
  441.     directory will be searched and its ancestors. If the file is 
  442.     not located this way, the search path (environment variable 
  443.     PATH) is used.
  444.  
  445.     This way of locating the file allows the programmer to write 
  446.     one command file which will be usable for a set of projects. 
  447.     It is then easy to provide a command file (with same name) 
  448.     locally for a project which needs special options.
  449.  
  450. 3.4.1.1  Example of command file search                              
  451.  
  452.  
  453.  
  454.                                                               6
  455.  
  456.  
  457.     Given the directories:
  458.  
  459.       /usr/prj1/liba
  460.       /usr/prj1/libb
  461.       /usr/prj1/libb/libb0
  462.       /usr/prj1/libb/libb1
  463.       /usr/prj1/libc
  464.       /usr/prj2/liba
  465.       /usr/prj2/libb
  466.       /usr/prj2/libc
  467.  
  468.     If we create these command files:
  469.  
  470.       /usr/proto.cfg
  471.       /usr/prj1/libb/proto.cfg
  472.       /usr/prj2/libc/proto.cfg
  473.  
  474.     The following list tells which file will be read if the 
  475.     command "proto @proto.cfg" is applied to each directory.
  476.  
  477.       /usr/prj1/liba          /usr/proto.cfg
  478.       /usr/prj1/libb/libb0    /usr/prj1/libb/proto.cfg
  479.       /usr/prj1/libb/libb1    /usr/prj1/libb/proto.cfg
  480.       /usr/prj1/libc          /usr/proto.cfg
  481.       /usr/prj2/liba          /usr/proto.cfg
  482.       /usr/prj2/libb          /usr/proto.cfg
  483.       /usr/prj2/libc          /usr/prj2/libc/proto.cfg
  484.       /lib/prjx               The environment variable PATH
  485.                               will be searched to locate proto.cfg
  486.                               the same way executable files are located.
  487.  
  488. 3.4.1.2  @ without file argument                                     
  489.  
  490.     If @ appears alone, the file 'proto.cfg' is implied. It will 
  491.     be looked for in the current directory. If not found, the .. 
  492.     directory will be searched, up to the root of the disk. If 
  493.     still not found, the PATH environment variable will be used.
  494.  
  495.     When proper proto.cfg files are created and dispatched to 
  496.     strategic locations within a file system, the command "proto 
  497.     @" is enough to extract prototypes of any project.
  498.  
  499. 3.4.2    -a : Default access control for member function (C++)       
  500.  
  501.     Member functions without access control specifier are 
  502.     normally set "private". Option -a records a different 
  503.     default.
  504.  
  505.       -a0 : private
  506.       -a1 : protected
  507.       -a2 : public
  508.  
  509.  
  510.  
  511.  
  512.  
  513.                                                               7
  514.  
  515.  
  516.     Added keywords PRIVATE, PROTECTED, and PUBLIC specify access 
  517.     control.
  518.  
  519. 3.4.3    -b : Update C++ header file from a .pm file                 
  520.  
  521.     Normally, proto output all class member function prototypes 
  522.     in a single file (see option -m0+, -m1+ and -c+). This file 
  523.     generally has the extension ".pm". From this file, proto 
  524.     distributes prototypes of class member functions in the 
  525.     header files that hold class definition. Option -b triggers 
  526.     this distribution.
  527.  
  528.     The syntax goes like this:
  529.  
  530.       -bheader_file+pm_file=destination_file
  531.       -bheader_file+pm_file
  532.       -bheader_file
  533.       -b
  534.  
  535.     If destination_file is omitted, header_file is used. If 
  536.     pm_file is omitted X.pm is used (where X is the name of the 
  537.     current directory). Option -b without argument is equivalent 
  538.     to -bX.hpp+X.pm or -bX.h+X.pm where X is the name of the 
  539.     current directory. X.h is used when X.hpp does not exist.
  540.  
  541.     Option -b may be used several times (to update different 
  542.     headers) on the same command line. Its action will be 
  543.     triggered only after the last prototype has been extracted.
  544.  
  545. 3.4.3.1  Example of option -b use                                    
  546.  
  547.     Given the command,
  548.  
  549.       proto -c+ -fx.pm *.c -bfile1.h+x.pm -bfile2.h+x.pm
  550.  
  551.     First, file x.h will be produced. It will contain all 
  552.     prototypes of class member functions. Then file file1.h and 
  553.     file2.h will be update. Prototypes will be distributed in 
  554.     the proper class declarations.
  555.  
  556. 3.4.3.2  Distribution control of class member prototypes in a file   
  557.  
  558.     Prototypes of class member functions must be distributed 
  559.     within the class definition. The extractor uses a simple way 
  560.     to locate the place those prototypes must be written.
  561.  
  562.     It simply locates paires of comments of this form:
  563.  
  564.       /*~PROTOBEG~ CLASS_NAME */
  565.       /*~PROTOEND~ */
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.                                                               8
  574.  
  575.  
  576.     Each comments must be alone in a source line. Everything 
  577.     that lies between those two comments has been placed by the 
  578.     extractor. Programmers should avoid writing between those 
  579.     comments, since proto replaces everything between, each time 
  580.     the file is update.
  581.  
  582. 3.4.4    -c : Output selection                                       
  583.  
  584.     PROTO can extract several things from C source files. Here 
  585.     is the list of what can be selected with the key letter used 
  586.     to specify it.
  587.  
  588.       e : Selection of export functions (extension to C).
  589.       o : Selection of ordinary functions.
  590.       p : Selection of "private" class member functions (C++).
  591.       p : Selection of "protected" class member functions (C++).
  592.       s : Selection of static functions.
  593.       u : Selection of "public" class member functions (C++).
  594.  
  595.       + : Selection of class member functions (C++).
  596.       d : Documentation (comments) surrounding the function definition.
  597.       i : Cross reference function vs source.
  598.  
  599.     The command "proto -cod *.c" will extract the prototypes and 
  600.     comments of every C source files of the current directory.
  601.  
  602. 3.4.4.1  Export : An extension to C                                  
  603.  
  604.     The export verb is an extension to C language. We have never 
  605.     seen a compiler implementing such verb. This verb is 
  606.     currently applied to function definitions, but may very well 
  607.     be applied to type definitions, constant definitions, 
  608.     variables, etc...
  609.  
  610.     This verb is a modifier like the static verb. This one 
  611.     limits the scope of an object to the source where it 
  612.     appears. Export specifies that the scope of the object 
  613.     crosses the system boundaries. An export function is an 
  614.     official service provided to users. An ordinary function is 
  615.     local to the system and must not be used by user's 
  616.     functions.
  617.  
  618. 3.4.4.1.1How to add export to C language                             
  619.  
  620.     Using the preprocessor, it is possible to add a dummy 
  621.     definition of the export verb. Just put the directive 
  622.     "#define export" in a header file, and include it in sources 
  623.     that use the verb.
  624.  
  625.     It is also possible to define the verb on the command line 
  626.     using the -d option supported by most compilers.
  627.  
  628. 3.4.4.1.2Why using export                                            
  629.  
  630.  
  631.  
  632.  
  633.  
  634.                                                               9
  635.  
  636.  
  637.     Export allows easy classification of the functions in a 
  638.     system. This helps users trying to locate a service. 
  639.     Generally the list of export functions is less than half the 
  640.     list of all system's functions. This helps as much for 
  641.     maintenance.
  642.  
  643. 3.4.4.1.3_export verb                                                
  644.  
  645.     The keyword _export is becoming popular while not standard, 
  646.     in several C compilers. Its use is similar to the export 
  647.     keyword already supported by the extractor. The two keywords 
  648.     are equivalent.
  649.  
  650. 3.4.4.2  Options -c and -f specified more than once                  
  651.  
  652.     Options -c and -f may be used more than once in a single 
  653.     command.
  654.  
  655.     Option -c sets an output selection which will be used by 
  656.     each following -f options, until a new -c option is met.
  657.  
  658.     The command "proto -co -fordin.h -cs -fstatic.h -cod 
  659.     -finfo.h *.c" produces three output files, each with a 
  660.     different content. This feature generally saves time in 
  661.     processing.
  662.  
  663. 3.4.4.3  Selection i of the -c option                                
  664.  
  665.     The selection 'i' allows the output of a cross reference 
  666.     function vs source. The following -f option will produce an 
  667.     index allowing a quick location of a function definition 
  668.     within a multiple sources project.
  669.  
  670.     The output file is an ASCII text file with a simple format:
  671.  
  672.       line_length!function_name!source_file_name
  673.  
  674.     The character '!' acts as delimiter. The line_length field 
  675.     gives the length of the line in bytes. This length is 
  676.     encoded in one single byte. Since the file is an ASCII text, 
  677.     the value 32 is added to the length yielding a printable 
  678.     character.
  679.  
  680.     This format has been chosen in order to allow processing of 
  681.     that file by simple programming language often found in 
  682.     programmer's editor.
  683.  
  684. 3.4.4.4  Selection d of the -c option                                
  685.  
  686.     The d selection orders the extraction of the function 
  687.     declaration and all surrounding comments.
  688.  
  689.     All contiguous comments immediatly preceding the function 
  690.     declaration and each comments met before the first brace '{' 
  691.     of the function body are grabbed and output along with the 
  692.     prototype.
  693.  
  694.  
  695.  
  696.                                                              10
  697.  
  698.  
  699.     The output file is an ASCII text file easily readable. It 
  700.     can be used as a preview of a system.
  701.  
  702. 3.4.4.5  Corrections to prototype before generation                  
  703.  
  704.     Some information may be omitted from a function declaration. 
  705.     The extractor automaticly adds what is missing.
  706.  
  707. 3.4.4.5.1Function without explicit return type                       
  708.  
  709.     If a function is declared without type, the extractor adds 
  710.     'int' to the prototype. The following declaration:
  711.  
  712.       max(int a, int b){ ... }
  713.  
  714.     produces the following prototype:
  715.  
  716.       int max(int a, int b);
  717.  
  718. 3.4.4.5.2Typeless parameters                                         
  719.  
  720.     If a parameter appears without typing, the keyword 'int' is 
  721.     inserted.
  722.  
  723.     Given the following function:
  724.  
  725.       int max (a,b){ ... }
  726.  
  727.     The following prototype will be produced:
  728.  
  729.       int max (int a, int b);
  730.  
  731. 3.4.4.5.3Function without parameter                                  
  732.  
  733.     The keyword 'void' will be automaticly inserted in the 
  734.     prototype of a function without parameter. The following 
  735.     declaration:
  736.  
  737.       int fct (){ ... }
  738.  
  739.     produces:
  740.  
  741.       int fct (void);
  742.  
  743. 3.4.5    -C : Disallow nested comments                               
  744.  
  745.     Proto allows nested comments. Option -C kills this feature.
  746.  
  747. 3.4.6    -d : Symbol definition                                      
  748.  
  749.  
  750.  
  751.  
  752.  
  753.                                                              11
  754.  
  755.  
  756.     The option -d allows the definition of preprocessor symbols 
  757.     on the command line.
  758.  
  759.     The option "-dsymxxx" is equivalent to "#define symxxx" 
  760.     within a source.
  761.  
  762.     The option "-dsymxxx=yyy" is equivalent to "#define symxxx 
  763.     yyy".
  764.  
  765. 3.4.7    -e : Close an output file                                   
  766.  
  767.     Option -e is used after option -f (+f) and terminates output 
  768.     to the file. This allows distribution of prototypes in 
  769.     different files, in a single processing.
  770.  
  771.     Example: proto -ffile1 a*.c -efile1 -ffile2 *.c
  772.  
  773.     File1 will hold only the prototypes of functions from 
  774.     sources "a*.c". File2 will contain all the other. Without 
  775.     option -e, file2 would have been a subset of file1.
  776.  
  777. 3.4.7.1  protection against processing twice the same file           
  778.  
  779.     The extractor won't process a file twice in a single work 
  780.     session. This allows processing a list of files with one set 
  781.     of options and the remaining files with an other set.
  782.  
  783.     The following command process the file xyz.c with a 
  784.     different set of options than the other files in the 
  785.     directory.
  786.  
  787.     proto -option ... -option xyz.c -option ... -option *.c
  788.  
  789.     Even if the list *.c includes xyz.c, this one won't be 
  790.     processed twice.
  791.  
  792. 3.4.7.1.1Source files spread in two directories                      
  793.  
  794.     Some large projects use so much disk space that a special 
  795.     handling is needed. One way is to put sources in one 
  796.     reference directory and let programmers import only the 
  797.     sources they modify into a personal directory. Some text 
  798.     editors handle this transparently by reading from the 
  799.     reference directory and saving to the personal directory.
  800.  
  801.     Given the /usr/src/x directory holding sources for project 
  802.     X. Given the programmer 'prog' who imports sources gradually 
  803.     as they are revised to directory /usr/prog/x.
  804.  
  805.     The command "proto *.c /usr/src/x/*.c" applied in 
  806.     /usr/prog/x directory will extract the prototypes of project 
  807.     X. The protection against double processing of a source is 
  808.     applied on the file's name, not on the file's path.
  809.  
  810. 3.4.8    -f/+f : Specification of an output file                     
  811.  
  812.  
  813.  
  814.  
  815.  
  816.                                                              12
  817.  
  818.  
  819.     The option -f may appear several times on the command line. 
  820.     Proto can produce several files in a single session.
  821.  
  822.     The option must be followed by an output file name. The 
  823.     option -f creats the file. The option +f appends to it.
  824.  
  825.     The format of the output depends on the last occurrence of 
  826.     the -c option.
  827.  
  828.     ex : "proto -cos -ffichier.p *.c" produces "fichier.p" with 
  829.     the prototypes of ordinary and static functions of the 
  830.     current directory.
  831.  
  832. 3.4.8.1  Options -c and -f specified more than once                  
  833.  
  834.     Options -c and -f may be used more than once in a single 
  835.     command.
  836.  
  837.     Option -c sets an output selection which will be used by 
  838.     each following -f options, until a new -c option is met.
  839.  
  840.     The command "proto -co -fordin.h -cs -fstatic.h -cod 
  841.     -finfo.h *.c" produces three output files, each with a 
  842.     different content. This feature generally saves time in 
  843.     processing.
  844.  
  845. 3.4.9    -h : Prototype file to split into class related header      
  846.  
  847.     Option -h reads a header file holding prototypes of member 
  848.     function (class member) and produces one header per classes. 
  849.     Proto builds the name of each header with the name of the 
  850.     class (truncated) and the extension ".pp".
  851.  
  852.     Those headers may be sub-included in the header that holds 
  853.     class definitions.
  854.  
  855.     -h must be followed without space by the name of the header 
  856.     to split. -h without argument specifies to split the file 
  857.     with the current directory name and the extension ".pm".
  858.  
  859.     The process will start after the last prototypes has been 
  860.     extracted.
  861.  
  862.     Option -h may be used several times on the command line.
  863.  
  864. 3.4.10   -i : Incremental mode                                       
  865.  
  866.     When -i is specified, proto reads the output files if they 
  867.     exist. If read is successful, only the source files that 
  868.     have changed are processed. All output files produced by 
  869.     proto hold the revision date of the original sources.
  870.  
  871.     This cuts the processing time quite a bit.
  872.  
  873. 3.4.11   -I : Search path for include files                          
  874.  
  875.  
  876.  
  877.  
  878.  
  879.                                                              13
  880.  
  881.  
  882.     The option -I specifies the list of directories to search in 
  883.     order to locate a header file (#include directive).
  884.  
  885.     This option may appear several times on the command line. 
  886.     Several directories may be specified in a single shot, each 
  887.     separated by a ':'.
  888.  
  889.     ex: -I/usr/include:/include <==> -I/usr/include -I/include
  890.  
  891. 3.4.12   -k : Renaming of keyword use by the extractor               
  892.  
  893.     Some keywords known to the extractor are not processed by 
  894.     all C and C++ compiler. The programmer must supplied null 
  895.     definition to the preprocessor for the compiler to "pass 
  896.     over it".
  897.  
  898.     These new keywords might generate conflict with existing 
  899.     programms. Some variable or type may share the same name. It 
  900.     is possible to rename those keywords or to disable them.
  901.  
  902.     Option -kxxx=yyy redefine keyword xxx as yyy. Option -kxxx 
  903.     just disable the keyword. Option -k may be used several 
  904.     times on the command line.
  905.  
  906.     Here an example where the keyword export conflict with a 
  907.     typedef. Since the typedef is used all around the project, 
  908.     the keyword export has to be rename to something else, say 
  909.     EXPORT. Option -lexport=EXPORT will disable export as a 
  910.     keyword, and EXPORT will inherit the meaning normally 
  911.     associated to export. So a declaration like this will work.
  912.  
  913.     EXPORT export *fct (void);
  914.  
  915. 3.4.13   -l : Alternate name for -h option                           
  916.  
  917.     Option -h may produce several header files. These files are 
  918.     named after the class name they belong to. Limitation of the 
  919.     file system forces option -h to truncated class name. This 
  920.     yields to conflicting names. Option -l specifies a file name 
  921.     to be used instead of the class name.
  922.  
  923.     Ex: proto -m0+ -lCLASS_SPEC1=class1.pp 
  924.     -lCLASS_SPEC2=class2.pp *.c -h
  925.  
  926.     Prototypes of member functions of class CLASS_SPEC1 will be 
  927.     output to file class1.pp and those of CLASS_SPEC2, to file 
  928.     class2.pp.
  929.  
  930. 3.4.14   -m : Prepackaged options combinations                       
  931.  
  932.     -m0 : Setup for single directory projects
  933.  
  934.       "proto -m0 *.c" applied to directory X is equivalent to
  935.       "proto -ceo -fX.p -ceod -fX.nap -ceoi -fX.nar *.c"
  936.  
  937.     -m1 : Setup for multiple directories projects
  938.  
  939.  
  940.  
  941.                                                              14
  942.  
  943.  
  944.       "proto -m1 *.c" applied to directory X is equivalent to
  945.       "proto -ceo -fX.p -ce  -f../include/X.p
  946.           -ceod -fX.nap -ced -f../doc/X.nap
  947.           -ceoi -fX.nar -cei -f../doc/X.nar *.c"
  948.  
  949. 3.4.14.1 Option -m1 : Optional output directory                      
  950.  
  951.     Directories ../include and ../doc are used as default by 
  952.     option -m1.
  953.  
  954.     If ../include does not exist, directory ../h is used instead 
  955.     One of these two directories must exist for -m1 to succeed.
  956.  
  957. 3.4.15   -o : Alternative name for option -m                         
  958.  
  959.     Option -m builds its output files from the current directory 
  960.     name. Option -o let you specify another base name.
  961.  
  962. 3.4.16   -p : Activate processing for following files                
  963.  
  964.     This option is used after option -x. It reactivates 
  965.     processing for each following source files on the command 
  966.     line.
  967.  
  968.     This is the default.
  969.  
  970. 3.4.16.1 Example of -p and -x uses                                   
  971.  
  972.     Some C files hold no useful prototypes. Some C files are 
  973.     produced by screen generators, grammar parsers, etc. These 
  974.     files are made up of large array declarations. It is 
  975.     sometime useful to skip these files while extracting the 
  976.     prototypes. This saves time.
  977.  
  978.     Given the two files screen1.c and screen2.c. The command 
  979.     "proto -x screen1.c screen2.c -p *.c" processes each source 
  980.     files in the current directory except these two.
  981.  
  982. 3.4.16.2 protection against processing twice the same file           
  983.  
  984.     The extractor won't process a file twice in a single work 
  985.     session. This allows processing a list of files with one set 
  986.     of options and the remaining files with an other set.
  987.  
  988.     The following command process the file xyz.c with a 
  989.     different set of options than the other files in the 
  990.     directory.
  991.  
  992.     proto -option ... -option xyz.c -option ... -option *.c
  993.  
  994.     Even if the list *.c includes xyz.c, this one won't be 
  995.     processed twice.
  996.  
  997. 3.4.17   -P : Preprocessor on                                        
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.                                                              15
  1004.  
  1005.  
  1006.     As a default, proto does not do macro replacement, nor 
  1007.     process #include directives. This allows quick extraction of 
  1008.     prototypes.
  1009.  
  1010.     Generally, ignoring macro replacement does not interfere and 
  1011.     proto produces correct results. There are few exceptions 
  1012.     where full preprocessing is essential for correct analysis 
  1013.     of function definitions.
  1014.  
  1015.     Option -P triggers a full ANSI C preprocessor (built-in). 
  1016.     However, options -I and -d must be specified properly.
  1017.  
  1018. 3.4.17.1 Processing of #define while full preprocessor is NOT active 
  1019.  
  1020.     #define directive are processed. This allows correct 
  1021.     evaluation of #ifdef directives.
  1022.  
  1023.     #undef directives are also processed.
  1024.  
  1025. 3.4.17.2 Processing of #if and #ifdef without -P option              
  1026.  
  1027.     When full preprocessing is off, processing of #if et #ifdef 
  1028.     may yield to incorrect results. Since header files are not 
  1029.     processed, replacement text of macros is unknown. The option 
  1030.     -d allows definition of macros on the command line, 
  1031.     partially solving the problem.
  1032.  
  1033. 3.4.18   Silent operation                                            
  1034.  
  1035.     Normally proto outputs on screen the list of every output 
  1036.     files. Option -s kills that feature.
  1037.  
  1038. 3.4.19   -t : source is read from the console (stdin)                
  1039.  
  1040.     Option -t tells proto to read one input file from the 
  1041.     keyboard (stdin). This allows pipes and easy testing.
  1042.  
  1043. 3.4.20   -v : List of source files processed                         
  1044.  
  1045.     Option -v displays every files processed.
  1046.  
  1047. 3.4.21   -x : Do not process following source files                  
  1048.  
  1049.     Each files specified after option -x on command line won't 
  1050.     be processed. Option -p puts proto back in normal state.
  1051.  
  1052.     The command "proto -x xxxx.c -p *.c" extracts prototypes of 
  1053.     all C source files except xxxx.c.
  1054.  
  1055. 3.4.21.1 Example of -p and -x uses                                   
  1056.  
  1057.     Some C files hold no useful prototypes. Some C files are 
  1058.     produced by screen generators, grammar parsers, etc. These 
  1059.     files are made up of large array declarations. It is 
  1060.     sometime useful to skip these files while extracting the 
  1061.     prototypes. This saves time.
  1062.  
  1063.  
  1064.  
  1065.  
  1066.                                                              16
  1067.  
  1068.  
  1069.     Given the two files screen1.c and screen2.c. The command 
  1070.     "proto -x screen1.c screen2.c -p *.c" processes each source 
  1071.     files in the current directory except these two.
  1072.  
  1073. 3.4.21.2 protection against processing twice the same file           
  1074.  
  1075.     The extractor won't process a file twice in a single work 
  1076.     session. This allows processing a list of files with one set 
  1077.     of options and the remaining files with an other set.
  1078.  
  1079.     The following command process the file xyz.c with a 
  1080.     different set of options than the other files in the 
  1081.     directory.
  1082.  
  1083.     proto -option ... -option xyz.c -option ... -option *.c
  1084.  
  1085.     Even if the list *.c includes xyz.c, this one won't be 
  1086.     processed twice.
  1087.  
  1088. 3.4.22   Macros and special character                                
  1089.  
  1090.     Some character strings have special meaning on command line. 
  1091.     This allows building commands generally usable.
  1092.  
  1093. 3.4.22.1 $ : current directory name                                  
  1094.  
  1095.     The current directory name is often used as the base name of 
  1096.     output files
  1097.  
  1098.     If one wishes to build a general script (batch file) to 
  1099.     extract prototypes, there must be a way to specify the 
  1100.     current directory name.
  1101.  
  1102.     The $ has been provided with a special meaning. It is 
  1103.     replaced by the name of the current directory.
  1104.  
  1105.     "proto -co -f$.p -cod -f$.nap -coi -f$.nar *.c" is 
  1106.     equivalent to "proto -m0 *.c".
  1107.  
  1108. 3.5      Invalid options combinations                                
  1109.  
  1110.     Several options are available. Several combinations are 
  1111.     meaningless.
  1112.  
  1113.     Some combinations are invalid and detected. An error is 
  1114.     written to the console. However some valid commands may 
  1115.     generate useless results.
  1116.  
  1117. 3.6      Suggested uses of the extractor                             
  1118.  
  1119.     Using the extractor is fairly simple. Just apply proto on 
  1120.     few sources and it creats header files.
  1121.  
  1122.     We have tried to provide the extractor with enough 
  1123.     flexibility to adjust for most methodologies.
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.                                                              17
  1130.  
  1131.  
  1132.     Here we will suggest a functional approach usable for small 
  1133.     projects (a single directory with few source files) and 
  1134.     larger ones.
  1135.  
  1136. 3.6.1    warning about this section                                  
  1137.  
  1138.     The following suggestions are not absolute solutions. We 
  1139.     have found these acceptable and useful. These come from 
  1140.     experience on different kind of projects.
  1141.  
  1142.     Other suggestions are welcome.
  1143.  
  1144. 3.6.2    The directory is the basic organizationnal unit             
  1145.  
  1146.     Systems are built from several source files (generally 10 to 
  1147.     30). Complex systems may be built from several directories. 
  1148.     Such systems are made of sub systems.
  1149.  
  1150.     From a user standpoint, complex or simple systems originate 
  1151.     from single directories. Complexity must be hidden to users. 
  1152.     Directories may hold sub-directories, but that does not 
  1153.     matter to users.
  1154.  
  1155.     The directory is then the basis of a naming convention: For 
  1156.     each system of a given name, there is a directory, a header 
  1157.     file and optionally an object library with the same name.
  1158.  
  1159. 3.6.3    Names for header file                                       
  1160.  
  1161.     For the sake of simplicity, header files available to users 
  1162.     have the name of the directory holding the project.
  1163.  
  1164.     So for a project X located in a directory X, every 'public' 
  1165.     header files will be named X.*.
  1166.  
  1167. 3.6.4    File locally generated                                      
  1168.  
  1169.     Option -m0 creates three files in the project directory. For 
  1170.     a directory X, files X.p, X.nap et X.nar are produced. 
  1171.     Option -m1 also creates these files and three others.
  1172.  
  1173.     X.p holds the prototypes. This file is sub-included by X.h, 
  1174.     the main header file of project X. The command '#include 
  1175.     "X.p"' is located at the end of X.h. Generally, prototypes 
  1176.     are placed directly into the main header file. This file 
  1177.     holds definitions and declarations. Since the extractor 
  1178.     can't write X.h without losing its content, an other file 
  1179.     must be created: X.p.
  1180.  
  1181. 3.6.5    Files exported to users                                     
  1182.  
  1183.     Option -m1 exports three files as well as three local files. 
  1184.     For a project X, a file X.p will written in the ../include 
  1185.     directory (or ../h) and files X.nap and X.nar will be 
  1186.     written in the ../doc directory. These files use the same 
  1187.     names as the local ones. These are restricted version of the 
  1188.     local files. They hold less functions.
  1189.  
  1190.  
  1191.  
  1192.                                                              18
  1193.  
  1194.  
  1195.     The export verb (extension to C) placed before a function 
  1196.     definition allows proto to classify functions available to 
  1197.     users.
  1198.  
  1199. 3.6.5.1  Export : An extension to C                                  
  1200.  
  1201.     The export verb is an extension to C language. We have never 
  1202.     seen a compiler implementing such verb. This verb is 
  1203.     currently applied to function definitions, but may very well 
  1204.     be applied to type definitions, constant definitions, 
  1205.     variables, etc...
  1206.  
  1207.     This verb is a modifier like the static verb. This one 
  1208.     limits the scope of an object to the source where it 
  1209.     appears. Export specifies that the scope of the object 
  1210.     crosses the system boundaries. An export function is an 
  1211.     official service provided to users. An ordinary function is 
  1212.     local to the system and must not be used by user's 
  1213.     functions.
  1214.  
  1215. 3.6.6    One header file, different views for users and members      
  1216.  
  1217.     For X directory, it exists one X.h header. Every sources of 
  1218.     the directory include that file. X.h includes X.p. Every 
  1219.     source has access to all prototypes of the system X.
  1220.  
  1221.     If X is a sub-system, X.h or a portion of it is exported to 
  1222.     the ../include. It becomes available to users. When a user 
  1223.     includes that file, this one includes ../include/X.p.
  1224.  
  1225.     Thus, users have access to prototypes of every export 
  1226.     functions of system X. Also the file ../doc/X.nap and 
  1227.     ../doc/X.nai may be read to get more information on 
  1228.     available functions.
  1229.  
  1230.     X.h conceptually unique, offers a different view to users 
  1231.     and members of the system X.
  1232.